Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Jump to bottom

style guide: no requirements in "Examples" sections #4382

Merged
merged 2 commits into from
Mar 2, 2025
Merged

style guide: no requirements in "Examples" sections #4382

merged 2 commits into from
Mar 2, 2025
+1 −0

Conversation

ralfhandl
Copy link
Contributor

@ralfhandl ralfhandl commented Feb 25, 2025 •
edited
Loading

Follow-up to #4339 (comment).

PR #4339 added text to an "Examples" section that used requirements language with "MUST" and "MAY". In this case the text was just copied verbatim from "non-example" sections of the spec, and no new requirements were added.

Better style is to

  • not to add requirements in a section called "Examples" or similar because readers may be confused whether these are really normative requirements or just explanations to the examples
  • not to use requirements language in explanations to examples

Tick one of the following options:

  • schema changes are included in this pull request
  • schema changes are needed for this pull request but not done yet
  • no schema changes are needed for this pull request

@ralfhandl ralfhandl added the editorial Wording and stylistic issues label Feb 25, 2025
@ralfhandl ralfhandl requested review from a team as code owners February 25, 2025 09:10
This was referenced Feb 25, 2025
Open
Open
lornajane
lornajane reviewed Feb 27, 2025
View reviewed changes
@lornajane
Copy link
Contributor

I tried to follow the thread of the other pull request, some comments, and what caused this change, but I'm not really clear, sorry. Could you add a note to the pull request description about what problem this solves or what we need to do or not do? I think it would help to inform the reviewer (me!)

@ralfhandl ralfhandl requested review from lornajane and a team February 28, 2025 08:23
lornajane
lornajane approved these changes Mar 2, 2025
View reviewed changes
Copy link
Contributor

@lornajane lornajane left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update and the description, feel much more confident that I know what I'm approving this time!

@lornajane lornajane merged commit 3e40ee4 into main Mar 2, 2025
4 checks passed
@lornajane lornajane deleted the ralfhandl-style-guide-no-requirements branch March 2, 2025 20:18
# for free to join this conversation on GitHub. Already have an account? # to comment
Reviewers

@lornajane lornajane lornajane approved these changes

Assignees
No one assigned
Labels
editorial Wording and stylistic issues
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@ralfhandl @lornajane